package edu.ipfw.cs590.cheat.services.mgmt;

/*
 * Course:    CS 590 Web Services
 * Semseter:  Spring 2009
 * Professor: Sedlemeyer
 * Project:   CHEAT (Code Help Educational Assignment Tool)
 * Due Date:  May 1, 2009
 * Team:      Sarcasm
 *            (Baker, Jason; Mitchell, Robin; Shie, Keith)
 *
 * Description:
 * This interface is the service is the single point of
 * interface into the CHEAT system.
 */


import edu.ipfw.cs590.cheat.services.AccessRights;
import edu.ipfw.cs590.cheat.services.Keyword;
import edu.ipfw.cs590.cheat.services.RegisteredPerson;
import java.util.List;
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;
import org.web_cat._1_0.assignment_sharing.Assignment;


/**
 *
 * @author rrm46582
 */
@WebService(name="AssignmentManagementInterface", targetNamespace="HTTP://cheat.cs590.ipfw.edu")
public interface AssignmentManagement
{

/**
 * RemoveAssignment:
 * This service removes an assignment from the repository.
 * Requires either ADMIN access or INST and must
 * be an author.
 *
 * @param token
 * @param removeUUID
 * @return
 * @throws SOAPFault containing a code mapped
 * AMSExceptionTypes
 */
    @WebMethod(operationName="RemoveAssignment")
    @WebResult(name="result")
    boolean removeAssignment(@WebParam(name="Token", header=true) String token, @WebParam (name="UUID") String removeUUID);




    /**
     * GetAssignment:
     * This service retrieves an assignment from the Repository.
     * Must be a registered user, no special access
     * is necessary.
     *
     * @param token
     * @param getUUID
     * @return
     * @throws SOAPFault containing a code mapped
     * AMSExceptionTypes
     */
    @WebMethod(operationName="GetAssignment")
    @WebResult(name="result")
    byte[] getAssignment(@WebParam(name="Token", header=true) String token, @WebParam(name="UUID") String getUUID);



    /**
     * SubmitAssignment:
     * This service allows a registered user who is also an INST
     * to submit an assignment to the repository
     *
     * @param token
     * @param assignmentArchive
     * @return
     * @throws SOAPFault containing a code mapped
     * AMSExceptionTypes
     */
    @WebMethod(operationName="SubmitAssignment")
    @WebResult(name="result")
    String submitAssignment(@WebParam(name="Token", header=true) String token, @WebParam(name="Archive") byte[] assignmentArchive);



   /**
    * ReplaceAssignment:
    * This service replaces an existing assignment with a new
    * assignment.  This requires INST access and must
    * also be an author of the target assignment
    *
    * @param token
    * @param replaceUUID
    * @param assignmentArchive
    * @return
    * @throws SOAPFault containing a code mapped
    * AMSExceptionTypes
    */
    @WebMethod(operationName="ReplaceAssignment")
    @WebResult(name="result")
    String replaceAssignment(@WebParam(name="Token" , header=true) String token, @WebParam(name="UUID") String replaceUUID, @WebParam(name="Archive") byte[] assignmentArchive);

    /**
     * Register:
     * This service creates a new RegisteredUser in a Pending state
     * This requires no special access.
     *
     * @param regUser
     * @return
     * @throws SOAPFault containing a code mapped
     * AMSExceptionTypes
     */
    @WebMethod(operationName="Register")
    @WebResult(name="RegisterResult")
    boolean register(@WebParam(name="RegistrationRequest") RegisteredPerson regUser);


    /**
     * GrantRegistrationRequest:
     * This service is used by a user who has ADMIN access
     * to promote a RegisteredUser from the Pending
     * state to the Active state.
     *
     * @param secToken
     * @param uuid
     * @return
     * @throws SOAPFault containing a code mapped
     * AMSExceptionTypes
     */
    @WebMethod(operationName="GrantRegistrationRequest")
    @WebResult(name="GrantResult")
    boolean grantRegistrationRequest(@WebParam(name="Token", header=true)String secToken, @WebParam(name="PendingUser") String uuid);


    /**
     * GetPandingRegistrationRequests:
     * This service retuns a list of all
     * the RegistreredUsers who are in the Pending state.
     * You must be a RegisteredUser with ADMIN access
     * to run this service.
     *
     * @param secToken
     * @return
     * @throws SOAPFault containing a code mapped
     * AMSExceptionTypes
     */
    @WebMethod(operationName="GetPendingRegistrationRequests")
    @WebResult(name="GetPendingResult")
    List<RegisteredPerson> getPendingRegistrationRequests(@WebParam(name="Token", header=true)String secToken);


    /**
    * DenyRegistrationRequest:
    * This service is used by a RegisteredUser who
    * has ADMIN access to deny a PendingUser
    * access as an Active RegisteredUser
     *
    * @param secToken
    * @param uuid
    * @return
    * @throws SOAPFault containing a code mapped
    * AMSExceptionTypes
    */
    @WebMethod(operationName="DenyRegistrationRequest")
    @WebResult(name="DenyResult")
    boolean denyRegistrationRequest( @WebParam(name="Token", header=true)String secToken, @WebParam(name="PendingUser") String uuid);


    /**
     * Login:
     * This service is used by a RegisteredUser to login to
     * the system.  By authenticating the user hass
     * access to all services that their access level
     * permits.
     *
     * @param userId
     * @param password
     * @return
     * @throws SOAPFault containing a code mapped
     * AMSExceptionTypes
     */
    @WebMethod(operationName="Login")
    @WebResult(name="LoginResult")
    String login(@WebParam(name="UserId") String userId, @WebParam(name="Password") String password);


    /**
     * Logout:
     * This service is used by an ActiveUser, who has previously
     * logged into the system, to disconnect and terminate their
     * session with the service architecture.
     *
     * @param secToken
     * @return true if successfully logged
     * otherwise returns a SOAPFault containing an
     * AMSExceptionTypes value
     */
    @WebMethod(operationName="Logout")
    @WebResult(name="LogoutResult")
    boolean logout(@WebParam(name="Token", header=true)String secToken);


    /**
     * GetAccessrights:
     * This service returns the access rights for
     * the given security token, secToken.  Access rights
     * are one of: the UserRights type Administrator, Instructor, Student
     *
     * @param secToken
     * @return returns an AccessRights object.
     * @throws SOAPFault containing a code mapped
     * AMSExceptionTypes
     */
    @WebMethod(operationName="GetAccessRights")
    @WebResult(name="AccessRightsResult")
    AccessRights getAccessRights(@WebParam(name="Token", header=true) String secToken);


    /**
     * GetPerson returns a RegisteredPerson as 
     * mapped by the passed in email address.
     * 
     * @param secToken
     * @param email
     * @return
     * @throws SOAPFault containing a code mapped
     * AMSExceptionTypes
     */
    @WebMethod(operationName="GetPerson")
    @WebResult(name="Person")
    RegisteredPerson getPerson(@WebParam(name="Token", header=true) String secToken, @WebParam(name="EMAIL") String email);


    /**
     * GetAssignmentMetaData:
     * This service returns the meta data of an assignment
     * as mapped by the passed in assignmentUUID
     *
     * @param assignmentUUID
     * @return
     * @throws SOAPFault containing a code mapped
     * AMSExceptionTypes
     */
    @WebMethod(operationName="GetAssignmentMetadata")
    @WebResult(name="MetadataResult")
    Assignment getAssignmentMetadata(@WebParam(name="UUID") String assignmentUUID);


    /**
     * GetAssignmentHistory:
     * This service returns all version history for a given 
     * assignment as mapped by the assignmentUUID
     * 
     * @param assignmentUUID
     * @return
     * @throws SOAPFault containing a code mapped
     * AMSExceptionTypes
     */
    @WebMethod(operationName="GetAssignmentHistory")
    @WebResult(name="HistoryResult")
    List<Assignment> getAssignmentHistory(@WebParam(name="UUID") String assignmentUUID);


    /**
     * GetAssignmentOwner:
     * This service will return the email address of a Registered user
     * who is an owner of the assignment as mapped by assignmentUUID.
     * 
     * @param assignmentUUID
     * @return
     * @throws SOAPFault containing a code mapped
     * AMSExceptionTypes
     */
    @WebMethod(operationName="GetAssignmentOwner")
    @WebResult(name="OwnerEmail")
    String getAssignmentOwner(@WebParam(name="UUID") String assignmentUUID);


    /**
     * FindAssignmentByLanguage:
     * This service can be used by any person, registerd or not, to search
     * the assignment meta data by programming language.  What is returned
     * is a list of Assignments whose structure corresponds to the 
     * assignment-sharing.xsd file
     * 
     * @param language
     * @return List<Assignment>
     * @throws SOAPFault containing a code mapped
     * AMSExceptionTypes
     */
    @WebMethod(operationName="FindAssignmentByLanguage")
    @WebResult(name="SearchResult")
    List<Assignment> findAssignmentByLanguage(@WebParam(name="Language") String languate);



    /**
     * FindAssignmentByKeyword:
     * This service can be used by any person, registerd or not, to search
     * the assignment meta data by a list of keyword values.  What is returned
     * is a list of Assignments whose structure corresponds to the
     * assignment-sharing.xsd file
     *
     * @param List<Keyword>
     * @return List<Assignment>
     * @throws SOAPFault containing a code mapped
     * AMSExceptionTypes
     */
    @WebMethod(operationName="FindAssignmentByKeyword")
    @WebResult(name="SearchResult")
    List<Assignment> findAssignmentByKeyword(@WebParam(name="Keywords") List<Keyword> keywords);


    /**
     * FindAssignmentByCourse:
     * This service can be used by any person, registerd or not, to search
     * the assignment meta data by course id.  What is returned
     * is a list of Assignments whose structure corresponds to the
     * assignment-sharing.xsd file
     *
     * @param course
     * @return List<Assignment>
     * @throws SOAPFault containing a code mapped
     * AMSExceptionTypes
     */
    @WebMethod(operationName="FindAssignmentByCourse")
    @WebResult(name="SearchResult")
    List<Assignment> findAssignmentByCourse(@WebParam(name="Course") String course);



    /**
     * FindAssignmentByAuthore:
     * This service can be used by any person, registerd or not, to search
     * the assignment meta data by an author's email address.  What is returned
     * is a list of Assignments whose structure corresponds to the
     * assignment-sharing.xsd file
     *
     * @param author
     * @return List<Assignment>
     * @throws SOAPFault containing a code mapped
     * AMSExceptionTypes
     */
    @WebMethod(operationName="FindAssignmentByAuthor")
    @WebResult(name="SearchResult")
    List<Assignment> findAssignmentByAuthor(@WebParam(name="Author") String author);




}
